home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Diamond Collection / The Diamond Collection (Software Vault)(Digital Impact).ISO / cdr47 / asmlib40.zip / DISK.DOC < prev    next >
Text File  |  1995-02-09  |  29KB  |  1,001 lines
  1.  
  2. ***************************** DISK & FILE *******************************
  3.  
  4. ASMLIB disk & file subroutines (C) Copyright 1992 - 1995 Douglas Herr
  5. All rights reserved
  6.  
  7. The MS-DOS file attribute byte tells you whether a file is read-only,
  8. system, a subdirectory, or may provide other information.  File attribute
  9. bits may be combined.  Each bit of the file attribute means:
  10.  
  11.         0 = normal files
  12.         1 = read-only
  13.         2 = hidden files
  14.         4 = system files
  15.         8 = volume label (only one per disk)
  16.        16 = subdirectories
  17.        32 = archive bit set
  18.  
  19.    Thus a file with an attribute of 18 is a hidden subdirectory (16 OR 2)
  20.  
  21.  
  22.  
  23.                       ASMLIB buffered file I/O system
  24.  
  25.     Several ASMLIB subroutines are available for buffered file Input or
  26.     Output.  Files to be managed by the buffered I/O system must be opened
  27.     by FOPEN or FCREATE, and must be closed by FCLOSE.  Buffered file I/O
  28.     will be much faster than unbuffered.  ASMLIB's default buffer size is
  29.     4096 bytes; this can be changed by altering FBUFFER_SIZE in FOPEN.ASM
  30.     and re-assembling.  Up to 20 files can be managed by FOPEN; this can
  31.     be changed by altering NUMBER_OF_FILES in $handle.asm and reassembling.
  32.     All ASMLIB file buffer subroutines assume DS:@data.
  33.  
  34.     To use the ASMLIB buffered I/O system excess DOS memory must be
  35.     released.  See ENDPROG in SYSTEM.DOC.
  36.  
  37.     Subroutines: FOPEN        open file & initialize buffer
  38.                  FCREATE      create file & initialize buffer
  39.                  FCLOSE       flush & close output buffer; close file
  40.                  FSEEK        move file pointer & update buffer
  41.                  FGET         read specified number of bytes from buffer
  42.                  FGETCHR      read a character from buffer
  43.                  FGETPOS      get file pointer position
  44.                  FGETSTR      read a string from buffer
  45.                  FGETSTRR     read previous string from buffer
  46.                  FPUTSTR      write string to buffer
  47.                  FPUTCRLF     write CR+LF to buffer
  48.                  FPUTCHR      write character to buffer
  49.                  FPUT         write specified number of bytes to buffer
  50.  
  51.  
  52. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  53.  
  54. DISKFREE:    determines free disk space
  55. Source:      diskfree.asm
  56.  
  57. Call with:   DL = drive number (drive A: = 0, default drive = -1)
  58. Returns:     if CF = 0, DX:AX = free disk space
  59.              if CF = 1, AX = DOS error code
  60.               DiskFree does not trap "drive not ready" errors
  61. Uses:        DX, AX, flags
  62. Supports:    all DOS drives
  63. Example:
  64.  
  65. include asm.inc
  66. public  example_code
  67.  
  68. .code
  69. example_code   proc
  70.         mov    dl,0
  71.         call    diskfree
  72.         jc      disk_error
  73.  
  74.  
  75. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  76.  
  77. DISKWP:      determines if a floppy disk is write-protected
  78. Source:      diskwp.asm
  79.  
  80. Call with:   DL = floppy disk number (drive A: = 0)
  81. Returns:     AL = BIOS error code
  82.                 0 = no error
  83.                 1 = invalid disk number
  84.                 3 = disk is write-protected
  85.               128 = drive not ready
  86. Uses:        AX, flags
  87. Supports:    physical drives A: and B:
  88. Example:
  89.  
  90. include asm.inc
  91.  
  92. public  mycode
  93. extrn   diskwp:proc
  94.  
  95. .code
  96. diskwp  proc
  97.         .
  98.         .
  99.         .
  100.         mov     dl,1        ; drive B:
  101.         call    diskwp      ; can I write to this disk?
  102.         or      al,al
  103.         jz      no_problem
  104.  
  105.  
  106. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  107.  
  108. DOTBAK:      changes the file extension of an existing file to .BAK
  109. Source:      dotbak.asm (strrchr.asm)
  110.  
  111. Call with:   DS:[SI] = address of a ASCIIZ valid filename
  112.              dotbak deletes a previous .BAK file of this name and
  113.              renames the input filename.ext to filename.bak.
  114. Returns:     if CF = 0, no error
  115.              if CF = 1, AL = DOS error code.  If AL = 5, the previous
  116.              .BAK filename is probably read-only.  All other errors refer
  117.              to the name change operation.
  118. Uses:        AX, flags
  119. Example:
  120.  
  121. extrn  dotbak:proc
  122.  
  123. .data
  124.  
  125. disk_doc  db 'DISK.DOC',0
  126.  
  127. .code
  128. ; program fragment assumes DS:@data
  129.              .
  130.              .
  131.              .
  132.              mov   si,offset DGROUP:disk_doc
  133.              call  dotbak
  134.  
  135.  
  136. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  137.  
  138. FCLOSE:      close a file managed by ASMLIB's buffered file I/O system
  139. Source:      fopen.asm ($handle.asm, allocdos.asm)
  140.  
  141. Call with:   BX = file handle
  142.              The file must have been opened by FOPEN or FCREATE;  If the
  143.              file is not read-only, the output buffer will be written to
  144.              the disk file before closing the file.
  145. Returns:     if CF = 0, no error
  146.              if CF = 1, AX = error code
  147. Uses:        AX, flags
  148. Example:     see FOPEN
  149.  
  150.  
  151.  
  152.  
  153. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  154.  
  155. FCOPY:       copy a file
  156. FCOPYM:      copy a file using supplied memory buffer
  157. Source:      fcopy.asm
  158.  
  159. Call with:   DS:[SI] = address of source filename
  160.              ES:[DI] = address of destination filename
  161.              Both filenames must be ASCIIZ strings.  Drive and path need
  162.              not be fully specified; filenames may not include * or ?
  163.              wildcards.
  164.              FCOPY only: Requires 64k DOS memory available
  165.              FCOPYM only: AX = segment address of 64k buffer
  166. Returns:     if CF = 0, no problem
  167.              if CF = 1, AX = DOS error code (AX = -1 if insufficient memory)
  168. Uses:        AX, CF
  169. Example:
  170.  
  171. .data
  172.         db 'b:'
  173. source  db 'asmlib.lib',0         ; copy the library to b:
  174.  
  175. extrn   fcopy:proc
  176. .code
  177. ; program fragment assumes DS:@data
  178.         .
  179.         .
  180.         push    ds
  181.         pop     es
  182.         assume es:@data
  183.         lea     si,source
  184.         mov     di,si                ; DI also points to source
  185.         sub     di,2                 ; back the pointer to the 'B:'
  186.         call    fcopy
  187.         jc      oops
  188.  
  189.  
  190.  
  191. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  192.  
  193. FCOUNT:      counts the number of files matching an ASCIIZ filespec string.
  194.              The filespec string may include the '*' and '?' wildcards.
  195. Source:      fcount.asm
  196.  
  197. Call with:   DS:[DX] pointing to filespec string
  198.              CX = file attributes
  199.              assumes DS:@data
  200. Returns:     AX = number of files matching the filespec string
  201. Uses:        AX, all other registers and flags are saved
  202. Example:
  203.  
  204. .code
  205. ; program fragment assumes DS:@data
  206.         .
  207.         .
  208.         .
  209.         lea    dx,filespec      ; address of filespec string
  210.         xor    cx,cx            ; normal files only
  211.         call   fcount
  212.  
  213.  
  214. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  215.  
  216. FCREATE:     create new file and initialize output buffer
  217. Source:      fcreate.asm ($handle.asm, allocdos.asm)
  218.  
  219. Call with:   DS:[DX] pointing to ASCIIZ filename
  220.              The file is created with write-only access.  If a file with
  221.              the same name already exists, it is truncated to zero
  222.              length by FCREATE.
  223. Returns:     if CF = 0, AX = file handle
  224.              if CF = 1, AX = error code
  225. Uses:        AX, flags
  226. Example:
  227.  
  228. include  asm.inc
  229.  
  230. public   myprog
  231. extrn    fcreate:proc
  232.  
  233. .data
  234. file_name   db 'ANYNEW.FIL',0
  235. file_handle dw 0
  236.  
  237. .code
  238. myprog   proc
  239. ; program fragment assumes DS:@data
  240.          .
  241.          .
  242.          .
  243.          lea   dx,file_name
  244.          call  fcreate
  245.          jc    something_went_wrong
  246.          mov   file_handle,ax ; save the handle
  247.          .
  248.          .
  249.          .
  250.  
  251.  
  252. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  253.  
  254. FEXIST:      determines if a file exists and can be opened with read access
  255. Source:      fexist.asm
  256.  
  257. Call with:   DS:[DX] pointing to ASCIIZ filename
  258. Returns:     if CF = 0, file exists
  259.              if CF = 1, AX = MS-DOS error code
  260. Uses:        AX, CF; all other flags and registers are saved
  261. Example:
  262.  
  263. include  asm.inc
  264.  
  265. extrn    fexist:proc
  266. .data
  267. filename db 'asmlib.doc',0
  268.  
  269. .code
  270. ; program fragment assumes DS:@data
  271.          .
  272.          .
  273.          .
  274.          lea   dx,filename
  275.          call  fexist
  276.          jnc   got_the_file      ; if CF = 0, go on
  277.          jmp   doserror          ; else go to error handling code
  278.  
  279.  
  280.  
  281. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  282.  
  283. FFLUSH:      flushes the ASMLIB and DOS output buffers for specified handle
  284. Source:      fflush.asm (fseek.asm, $handle.asm)
  285.  
  286. Call with:   BX = file handle
  287.              flushing the buffers guards against data loss in case of system
  288.              failure, such as power loss
  289. Returns:     if CF = 0, no error; function successful
  290.              if CF = 1, AX = DOS error code
  291. Uses:        AX, flags
  292. Example:
  293.  
  294. include asm.inc
  295.  
  296. extrn fflush:proc
  297.  
  298. .code
  299. ; program opens file & writes to file
  300.       .
  301.       .
  302.       .
  303. ; flush the buffers to disk
  304.       mov    bx,handle
  305.       call   fflush
  306.  
  307.  
  308.  
  309. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  310.  
  311. FGET:        read specified number of bytes from file buffer
  312. Source:      fget.asm ($handle.asm, $fget.asm)
  313.  
  314. Call with:   BX = file handle
  315.              CX = number of bytes requested (up to 4096 bytes)
  316. Returns:     if CF = 0, AX = number of bytes read
  317.                         ES:[BX] points to data in buffer
  318.              if CF = 1, AX = DOS error code
  319. Uses:        AX, BX, ES, flags
  320. Example:
  321.  
  322. include   asm.inc
  323.  
  324. extrn     fopen:proc, fget:proc
  325.  
  326. .data
  327. file_name   db 'asmlib.doc',0
  328. file_handle dw 0
  329.  
  330. .code
  331. ; program fragment assumes DS:@data
  332.           .
  333.           .
  334.           .
  335.           lea   dx,file_name
  336.           call  fopen
  337.           jc    fopen_problem
  338.           mov   file_handle,ax  ; save for later
  339.  
  340.           mov   bx,ax           ; file handle
  341.           mov   cx,8            ; I want 8 bytes
  342.           call  fget            ;  returned at ES:[BX]
  343.           jc    read_problem    ; uh oh, trouble ...
  344.           cmp   ax,cx           ; did I get what I wanted?
  345.           jne   not_enough
  346.           .
  347.           .
  348.  
  349.  
  350.  
  351.  
  352. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  353.  
  354. FGETCHR:     read a character from a file buffer
  355. Source:      fgetchr.asm ($handle.asm)
  356.  
  357. Call with:   BX = file handle
  358. Returns:     if CF = 0, AL = next character from file buffer
  359.              if CF = 1, AX = DOS error code
  360.                         AX = 0 if at end of file
  361. Uses:        AX, flags
  362. Example:
  363.  
  364. include   asm.inc
  365.  
  366. extrn     fopen:proc, fgetchr:proc
  367.  
  368. .data
  369. file_name   db 'asmlib.doc',0
  370. file_handle dw 0
  371.  
  372. .code
  373. ; program fragment assumes DS:@data
  374.           .
  375.           .
  376.           .
  377.           lea   dx,file_name
  378.           call  fopen
  379.           jc    fopen_problem
  380.           mov   file_handle,ax  ; save for later
  381.  
  382.           mov   bx,ax           ; file handle
  383.           call  fgetchr         ; character in AL
  384.           jc    read_problem
  385.  
  386.           .
  387.           .
  388.  
  389.  
  390.  
  391. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  392.  
  393. FGETPOS:     determine file pointer position for file managed by library
  394. Source:      fgetpos.asm ($handle.asm)
  395.  
  396. Call with:   BX = file handle
  397.              Also works with file not opened by FOPEN or FCREATE.
  398. Returns:     if CF = 0, DX:AX = file pointer position
  399.              if CF = 1, AX = DOS error code
  400. Uses:        AX, DX, flags
  401. Example:
  402.  
  403. include asm.inc
  404.  
  405. extrn   fopen:proc, fgetstr:proc, fpetpos:proc
  406.  
  407. .code
  408. ; program fragment assumes DS:@data
  409.         .
  410.         .
  411.         .
  412. ; program opens file & does a variety of read & write operations
  413. ; get pointer position
  414.         mov     bx,handle
  415.         call    fgetpos            ; get position in DX:AX
  416.         jc      uh_oh
  417.  
  418.  
  419.         
  420. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  421.  
  422. FGETSTR:     read an ASCII string from a file buffer
  423. Source:      fgetstr.asm ($handle.asm, $fget.asm)
  424.  
  425. Call with:   BX = file handle
  426.              ASCII strings may be terminated with either 0Dh or 0Dh+0Ah.
  427.              After reading each string, FGetStr positions the buffer pointer
  428.              to read the next string.  String length should be less than
  429.              the buffer size.  See FOPEN.
  430. Returns:     if CF = 0, ES:[BX] points to string in buffer
  431.                         CX = length of ASCII string
  432.                      if CX = byte length of buffer, string >= size of buffer
  433.              if CF = 1, AX = DOS error code
  434.                         AX = 0 if end of file
  435. Uses:        ES, BX, AX, CX, flags
  436. Example:
  437.  
  438. include   asm.inc
  439.  
  440. extrn     fopen:proc, fgetstr:proc
  441.  
  442. .data
  443. file_name   db 'asmlib.doc',0
  444. file_handle dw 0
  445.  
  446. .code
  447. ; program fragment assumes DS:@data
  448.           .
  449.           .
  450.           .
  451.           lea   dx,file_name
  452.           call  fopen
  453.           jc    fopen_problem
  454.           mov   file_handle,ax  ; save for later
  455.  
  456.           mov   bx,ax           ; file handle
  457.           call  fgetstr
  458.           jc    read_problem
  459.  
  460.           call  strndup         ; make a copy in near heap for later
  461.           .
  462.           .
  463.           .
  464.  
  465.  
  466.  
  467. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  468.  
  469. FGETSTRR:    read previous ASCII string from a file buffer
  470. Source:      fgetstr.asm ($handle.asm, $fget.asm, fgetpos.asm)
  471.  
  472. Call with:   BX = file handle
  473.              ASCII strings may be terminated with either 0Dh or 0Dh+0Ah.
  474.              After reading each string, FGetStrR positions the buffer pointer
  475.              to read the previous string.  String length should be less than
  476.              the buffer size.  See FOPEN.
  477.              Note that FGetStrR positions the file pointer to read the next
  478.              previous string; if you call FGetStr after calling FGetStrR,
  479.              FGetStr will return the same string returned by the preceeding
  480.              FGetStrR.
  481. Returns:     if CF = 0, ES:[BX] points to string in buffer
  482.                         CX = length of ASCII string
  483.                      if CX = byte length of buffer, string >= size of buffer
  484.              if CF = 1, AX = DOS error code
  485.                         AX = 0FFFFh if file pointer at start of file
  486. Uses:        ES, BX, AX, CX, flags
  487. Example:
  488.  
  489. include   asm.inc
  490.  
  491. extrn     fopen:proc, fgetstrr:proc
  492.  
  493. .data
  494. file_name   db 'asmlib.doc',0
  495. file_handle dw 0
  496.  
  497. .code
  498. ; program fragment assumes DS:@data
  499.           .
  500.           .
  501.           .
  502.           lea   dx,file_name
  503.           call  fopen
  504.           jc    fopen_problem
  505.           mov   file_handle,ax  ; save for later
  506.  
  507.           mov   bx,ax           ; file handle
  508.           call  fgetstrr
  509.           jc    read_problem  ; AX = 0FFFFh if at start of file
  510.  
  511.           call  strndup         ; make a copy in near heap for later
  512.           .
  513.           .
  514.           .
  515.  
  516.  
  517.  
  518. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  519.  
  520. FILELIST:    creates a list of file names matching a filespec mask
  521. Source:      filelist.asm (fcount.asm, allocdos.asm)
  522.  
  523. Call with:   DS:[SI] pointing to filespec mask
  524.              CX = file attribute mask
  525. Returns:     if CF = 0:
  526.                ES = base segment address of list buffer
  527.                AX = number of filenames in list
  528.                CX = list field width
  529.              if CF = 1, AX = MS-DOS error code
  530.              You should use DOS function 49h to release the file list
  531.              buffer when you're done with it.
  532. Uses:        AX, CX, ES, CF
  533. Example:
  534.  
  535. include asm.inc
  536.  
  537. public  myproc
  538.  
  539. .data
  540. filespec db '*.*',0
  541.  
  542. .code
  543. ; program fragment assumes DS:@data
  544.         .
  545.         .
  546.         .
  547.         lea    si,filespec
  548.         mov    cx,16            ; normal files and subdirectories
  549.         call   filelist
  550.         jc     cant_do_it       ; oops
  551.  
  552.  
  553.  
  554. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  555.  
  556. FINDDATE:    given a successful call to FindFirst or FindNext, returns
  557.              the file's date stamp
  558. Source:      findfile.asm
  559.  
  560. Call with:   DS:[BX] pointing to DTA buffer; assumes DS  @DATA
  561. Returns:     DX = month
  562.              AX = day
  563.              CX = year
  564. Uses:        AX, CX, DX, flags
  565. Example:
  566.  
  567. .code
  568. ; program fragment assumes DS:@data
  569.         .
  570.         .
  571.         .
  572.         lea    bx,filespec
  573.         mov    cx,0              ; normal files only
  574.         call   findfirst         ; find first matching file
  575.         jc     no_more_files
  576.         cmp    ax,-1
  577.         je     no_more_files
  578.         call   finddate
  579.  
  580.  
  581.  
  582. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  583.  
  584. FINDFIRST:   This subroutine, when used with FindNext, finds files on
  585.              a disk which match an ASCIIZ filespec string.  The filespec
  586.              string may contain the '*' and '?' wildcards.
  587. Source:      findfile.asm (heap.asm)
  588.  
  589. Call with:   DS:[BX] pointing to ASCIIZ filespec string; assumes DS:@data
  590.              CX = file attribute mask
  591.  
  592.              FindFirst allocates space for a local DTA buffer from the
  593.              near heap.  See FindNext; also see MEMINIT.
  594.  
  595. Returns:     AX = error code
  596.              -1 = insufficient memory in near heap (128 bytes required)
  597.              0 = no error
  598.              CF = 1 if no files match the filespec string
  599.              DS:[BX] -> DTA buffer if the subroutine is successful.  Do not
  600.              alter the 128 bytes in the DTA buffer.
  601.              The name of the file is an ASCIIZ string at 30[BX]
  602.              The file attribute is a byte at 21[BX]
  603.              The low word of the file's size is at 26[BX]
  604.              The high word of the file's size is at 28[BX]
  605. Uses:        AX, BX, flags
  606. Example:
  607.  
  608. .code
  609. ; program fragment assumes DS:@data
  610.      .
  611.      .
  612.      .
  613.      lea    bx,filespec
  614.      mov    cx,0              ; normal files only
  615.      call   findfirst         ; find first matching file
  616.      jc     no_more_files
  617.      cmp    ax,-1
  618.      je     no_memory         ; memory not available
  619.  
  620. ; print the filename on the screen
  621. tprint_next:
  622.      mov    si,bx
  623.      add    si,30             ; point to filename in DTA buffer
  624.      mov    dh,count          ; row value
  625.      mov    dl,0              ; column 0
  626.      mov    ah,12             ; color attribute - RED!
  627.      call   tprint            ; display the file name on the screen
  628.      inc    count             ; next filename on next row
  629.      call   findnext          ; any more matching filenames?
  630.      jnc    tprint_next
  631. no_more_files:
  632.  
  633. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  634.  
  635. FINDNEXT:    finds file matching search string; use after FindFirst.
  636.              used only after a successful call to FindFirst.
  637. Source:      findfile.asm (heap.asm)
  638.  
  639. Call with:   no parameters; assumes DS:@data
  640.  
  641.              FindNext de-allocates the DTA buffer space after the first
  642.              unsuccessful search for a matching file.
  643.  
  644. Returns:     DS:[BX] -> DTA buffer
  645.              CF = 1 if no more files match the filespec string.
  646. Uses:        BX, flags
  647. Example:     see FindFirst.
  648.  
  649.  
  650. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  651.  
  652. FINDTIME:    given a successful call to FindFirst or FindNext, returns
  653.              the file's time stamp
  654. Source:      findfile.asm
  655.  
  656. Call with:   DS:[BX] pointing to DTA buffer; assumes DS:@data
  657. Returns:     DX = hour
  658.              AX = minute
  659.              CX = second
  660. Uses:        AX, CX, DX, flags
  661. Example:     lea    bx,filespec
  662.              mov    cx,0              ; normal files only
  663.              call   findfirst         ; find first matching file
  664.              jc     no_more_files
  665.              cmp    ax,-1
  666.              je     no_more_files
  667.              call   findtime
  668.  
  669.  
  670.  
  671. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  672.  
  673. FLOAD:       read a file into far memory
  674. Source:      fload.asm (fsize.asm, allocdos.asm)
  675.  
  676. Call with:   DS:[DX] pointing to ASCIIZ filename
  677. Returns:     if CF = 0, BX = initial segment address of memory block
  678.                         DX:AX = bytes loaded from disk
  679.              if CF = 1, AX = DOS error code
  680. Uses:        AX, BX, DX, CF
  681. Example:
  682.  
  683. include asm.inc
  684.  
  685. public  test_fload
  686.  
  687. extrn   fload:proc
  688.  
  689. .data
  690. fileseg         dw 0
  691. fname           db 'filename.txt',0
  692. file_size       dw 0,0
  693.  
  694. .code
  695. test_fload      proc
  696. ; program fragment assumes DS:@data
  697.         .
  698.         .
  699.  
  700.         lea     dx,fname
  701.         call    fload           ; read file into DOS memory
  702.         jc      no_good         ;  jump if there was a problem
  703.  
  704.         mov     fileseg,bx      ; save initial segment address
  705.                                 ; of allocated memory
  706.         mov     file_size,ax    ; save file size
  707.         mov     file_size+2,dx
  708.  
  709. no_good:                        ; return with CF = 1 if error
  710.         ret                     ; CF = 0 if no error
  711. test_fload      endp
  712.         end
  713.  
  714.  
  715.  
  716. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  717.  
  718. FOPEN:       opens existing file and initializes ASMLIB buffered I/O
  719. Source:      fopen.asm (allocdos.asm, $handle.asm)
  720.  
  721. Call with:   DS:[DX] pointing to name of file to be opened
  722.              AL = access mode
  723.               0 = read-only access
  724.               1 = write-only access
  725.               2 = read-write access NOT SUPPORTED YET
  726. Returns:     if CF = 0, AX = file handle
  727.              if CF = 1, AX = ASMLIB or DOS error code; file not opened
  728.                 if AX = 0, insufficient DOS memory available
  729.                 if AX = 0FFFFh, no handles available in ASMLIB I/O array;
  730.                    change NUMBER_OF_HANDLES in $handle.asm amd re-assemble
  731.                    (default = 20 handles)
  732. Uses:        AX, flags
  733. Example:
  734.  
  735. include  asm.inc
  736.  
  737. public   myprog
  738. extrn    fopen:proc, fclose:proc
  739.  
  740. .data
  741. file_name   db 'ASMLIB.DOC',0
  742. file_handle dw 0
  743.  
  744. .code
  745. myprog   proc
  746. ; program fragment assumes DS:@data
  747.          .
  748.          .
  749.          .
  750.          lea   dx,file_name
  751.          xor   al,al          ; read-only access
  752.          call  fopen
  753.          jc    something_went_wrong
  754.          mov   file_handle,ax ; save the handle
  755.          .
  756.          .
  757.          .
  758.  
  759. ; all done with this file
  760.          mov   bx,file_handle
  761.          call  fclose
  762.  
  763.  
  764.  
  765. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  766.  
  767. FPUT:        write specified number of bytes to output file buffer
  768. Source:      fput.asm ($handle.asm)
  769.  
  770. Call with:   BX = file handle
  771.              ES:[DI] pointing to data to write
  772.              CX = number of bytes to write
  773. Returns:     if CF = 0, no error
  774.              if CF = 1, AX = error code
  775. Uses:        AX, flags
  776. Example:
  777.  
  778. include  asm.inc
  779.  
  780. public   myproc
  781. extrn    fput:proc
  782. extrn    fputchr:proc
  783. extrn    fputcrlf:proc
  784.  
  785. .data
  786. data1    db 'several bytes may be written at once'
  787. data_len equ $-data1
  788.  
  789. .code
  790. ; program fragment assumes DS:@data
  791.          .
  792.          .
  793.          .
  794.          mov   bx,output_handle
  795.          push  ds
  796.          pop   es                     ; ES = DS = DGROUP
  797.          assume  es:DGROUP
  798.          lea   di,data1               ; ES:[DI] -> data1
  799.          mov   cx,data_len            ; bytes to write
  800.          call  fput
  801.          call  fputcrlf               ; write CR+LF for new line
  802.                                       ; in ASCII text file
  803.          mov   al,26                  ; End-of-File byte (optional)
  804.          call  fputchr
  805.  
  806.  
  807. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  808.  
  809. FPUTCHR:     write one character to output file buffer
  810. Source:      fputchr.asm (fput.asm)
  811.  
  812. Call with:   BX = output file handle
  813.              AL = character to write
  814. Returns:     if CF = 1, AX = MS-DOS error code
  815.              if CF = 0, no error
  816. Uses:        AX, flags
  817. Example:     see FPUT
  818. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  819.  
  820. FPUTCRLF:    write CR+LF pair to output file buffer
  821. Source:      fputcrlf.asm (fput.asm)
  822.  
  823. Call with:   BX = output file handle; file must have been opened by
  824.              FOPEN or FCREATE
  825. Returns:     if CF = 0, no error
  826.              if CF = 1, AX = DOS error code
  827. Uses:        AX, flags
  828. Example:     see FPUT
  829.  
  830.  
  831.  
  832. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  833.  
  834. FPUTSTR:     write an ASCIIZ string to output buffer
  835. Source:      fpustr.asm (strlen.asm, fput.asm)
  836.  
  837. Call with:   BX = file handle
  838.              ES:[DI] points to ASCIIZ string
  839. Returns:     if CF = 0, AX = bytes written
  840.              if CF = 1, AX = DOS error code
  841. Uses:        AX, flags
  842. Example:
  843.  
  844. include  asm.inc
  845.  
  846. public   myproc
  847. extrn    fputstr:proc
  848. extrn    fputcrlf:proc
  849.  
  850. .data
  851. strptr   dw 0                      ; pointer to string, assigned by program
  852.  
  853. .code
  854. ; program fragment assumes DS:@data
  855.          .
  856.          .
  857.          .
  858.          push  ds
  859.          pop   es                     ; ES = DS = DGROUP
  860.          assume  es:DGROUP
  861.          mov   bx,output_handle
  862.          mov   di,strptr              ; ES:[DI] -> data1
  863.          call  fputstr
  864.          call  fputcrlf               ; write CR+LF for new line
  865.                                       ; in ASCII text file
  866.  
  867.  
  868.  
  869. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  870.  
  871. FSEEK:       move file pointer for a file opened by FOPEN
  872. Source:      fseek.asm ($handle.asm)
  873.  
  874. Call with:   BX = file handle
  875.              AL = method code: 0 = absolute offset from start of file
  876.                                1 = signed offset from current file pointer
  877.                                2 = signed offset from end of file
  878.              CX:DX = dword offset
  879. Returns:     if CF = 1, AX = DOS error code
  880.              if CF = 0, DX:AX = current location of file pointer
  881. Uses:        AX, DX, flags
  882.  
  883. Example:
  884.  
  885. include   asm.inc
  886.  
  887. public  whoknows
  888.  
  889. extrn fopen:proc, fseek:proc
  890.  
  891. .data
  892. file0   db 'file0.dat',0
  893.  
  894. .code
  895. whoknows  proc
  896. ; program fragment assumes DS:@data
  897.         .
  898.         .
  899.         .
  900.         mov     dx,offset DGROUP:file0
  901.         mov     al,1              ; write only
  902.         call    fopen
  903.         jc      error
  904.         xor     cx,cx
  905.         mov     dx,cx             ; zero offset
  906.         mov     al,2              ; relative to end of file
  907.         call    fseek             ; move pointer to end of file
  908.  
  909.  
  910.  
  911.  
  912.  
  913. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  914.  
  915. FSIZE:       determines a file's size
  916. Source:      fsize.asm
  917.  
  918. Call with:   BX = valid file handle
  919. Returns:     if CF = 0, DX:AX = file size
  920.              if CF = 1, AX = MS-DOS error code
  921. Uses:        AX, DX, CF
  922. Example:
  923.  
  924. include asm.inc
  925.  
  926. extrn   fsize:proc
  927.  
  928. .data
  929. filenam db 'ASMLIB.DOC',0      ; ASCIIZ filename
  930.  
  931. .code
  932.         .
  933.         .
  934.         .
  935.         lea     dx,filenam     ; point to filename
  936.         mov     ax,3D00h       ; MS-DOS open file function, read-only
  937.         int     21h
  938.         jc      oops           ; jump to error control
  939.                                ; else no problem - continue
  940.         mov     bx,ax          ; file handle in BX
  941.         call    fsize
  942.  
  943.  
  944. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  945.  
  946. GOODDRIVE:   determines if a drivespec is a valid DOS drive
  947.              includes RAM disks and network drives
  948. Source:      goodrive.asm
  949.  
  950. Call with:   DL = drive code
  951.               0 = A:
  952.               1 = B:
  953.               2 = C:
  954.                etc.
  955. Returns:     if CF = 0, the drive is a valid DOS drive
  956.              if CF = 1, the drivespec is not valid
  957. Uses:        flags
  958. Example:
  959.  
  960. include asm.inc
  961.  
  962. extrn   gooddrive.asm
  963.  
  964. .code
  965.         .
  966.         .
  967.         .
  968.         mov    dl,3          ; see if a D: drive exists on this computer
  969.         call   gooddrive
  970.         jc     no_good       ; no D: drive
  971.  
  972.  
  973. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  974.  
  975. QFNAME:      qualifies a filename
  976. Source:      qfname.asm
  977.  
  978. Call with:   DS:[BX] pointing to a filename; the filename may contain
  979.              drive specification and/or complete or partial path name.
  980.              Drive specification and path name not required.
  981. Returns:     DS:[SI] pointing to the full DRIVESPEC:\PATH\FILENAME
  982.              CX = length of full filename
  983.              Note that DS:[SI] points to QFName's buffer space; the next
  984.              call to QFName will return a new filename at the same address.
  985. Uses:        SI, CX, flags
  986. Example:
  987.  
  988. include asm.inc
  989.  
  990. .data
  991. docs   db '*.doc',0         ; search for .DOC files in current directory
  992.  
  993. .code
  994. ; program fragment assumes DS:@data
  995.        .
  996.        .
  997.        .
  998.        lea    bx,docs
  999.        call   qfname
  1000.  
  1001.